Working With Sound Channels
Sequence grabber components provide a number of functions that allow you to configure the grabber's sound channels. This section describes these configuration functions, which you can use only with sound channels. You can determine whether a channel has a sound representation by calling the
SGGetChannelInfo
function, described on
SGGetChannelInfo
. If you want to configure a video channel, use the functions described in
"Working With Video Channels,"
. If you want to configure general attributes of a channel, use the functions described in
"Working With Channel Characteristics,"
.
Use the
SGSetSoundInputDriver
function to specify a channel's sound input device. You can determine a channel's sound input device by calling the
SGGetSoundInputDriver
function. If you change any attributes of the sound input device, you should notify the sequence grabber component by calling the
SGSoundInputDriverChanged
function. By default, the sequence grabber component uses the sound driver's best settings.
You can control the amount of sound data the sequence grabber works with at one time by calling the
SGSetSoundRecordChunkSize
function. You can determine this value by calling the
SGGetSoundRecordChunkSize
function.
You can control the rate at which the sound channel samples the input data by calling the
SGSetSoundInputRate
function. You can determine the sample rate by calling the
SGGetSoundInputRate
function.
You can control other sound input parameters by using the
SGSetSoundInputParameters
and
SGGetSoundInputParameters
functions.
SGSetSoundInputDriver
Some sound channel components may use sound input devices to obtain their source data. The
SGSetSoundInputDriver
function allows you to assign a sound input device to a sound channel.
pascal ComponentResult SGSetSoundInputDriver (SGChannel c,
ConstStr255Param driverName);
-
c
-
Specifies the reference that identifies the channel for this operation. You obtain this reference from the
SGNewChannel
function, described on
SGNewChannel
.
-
driverName
-
Specifies the name of the sound input device. This is a Pascal string, and it must correspond to a valid sound input device.
DESCRIPTION
If the sound channel component does not use sound input devices, it returns a nonzero result code. For more information about sound input devices, see
Inside Macintosh: More Macintosh Toolbox
--in particular, refer to the discussion of the Sound Manager's
SPBGetIndexedDevice
routine.
SPECIAL CONSIDERATIONS
You cannot call the
SGSetSoundInputDriver
function during a record operation.
RESULT CODES
|
noDeviceForChannel
|
-9400
|
Channel component cannot find its device
|
|
cantDoThatInCurrentMode
|
-9402
|
Request invalid in current mode
|
|
deviceCantMeetRequest
|
-9408
|
Device cannot support grabber
|
SGGetSoundInputDriver
The
SGGetSoundInputDriver
function allows you to determine the sound input device currently in use by a sound channel component.
pascal long SGGetSoundInputDriver (SGChannel c);
-
c
-
Specifies the reference that identifies the channel for this operation. You obtain this reference from the
SGNewChannel
function, described on
SGNewChannel
.
DESCRIPTION
The
SGGetSoundInputDriver
function returns a reference to the sound input device. If the sound channel is not using a sound input device, this returned value is set to
nil
.
You may want to gain access to the sound input device if you want to change the device's configuration.
SPECIAL CONSIDERATIONS
If you change any of the device's operating parameters, be sure to inform the sequence grabber component by calling the
SGSoundInputDriverChanged
function, which is described in the next section.
SEE ALSO
You can assign a sound input device to a sound channel by calling the
SGSetSoundInputDriver
function, described in the previous section.
SGSoundInputDriverChanged
The
SGSoundInputDriverChanged
function allows you to notify the sequence grabber component whenever you change the configuration of a sound channel's sound input device.
pascal ComponentResult SGSoundInputDriverChanged (SGChannel c);
-
c
-
Specifies the reference that identifies the channel for this operation. You obtain this reference from the
SGNewChannel
function, described on
SGNewChannel
.
DESCRIPTION
The sequence grabber's sound channels maintain information about the configuration of any sound input devices that are currently in use. It is very important to notify the sequence grabber component of any configuration changes you make.
SPECIAL CONSIDERATIONS
You should not change the configuration of the sound input device during a record operation.
SEE ALSO
You can obtain access to a sound channel's sound input device by calling the
SGGetSoundInputDriver
function, which is described in the previous section.
SGSetSoundRecordChunkSize
During record operations, the sequence grabber works with groups of sound samples. These groups are referred to as
chunks
. By default, each chunk contains two seconds of sound data. Smaller chunks use less memory. You can control the amount of sound data in each chunk by calling the
SGSetSoundRecordChunkSize
function.
pascal ComponentResult SGSetSoundRecordChunkSize (SGChannel c,
long seconds);
-
c
-
Specifies the reference that identifies the channel for this operation. You obtain this reference from the
SGNewChannel
function, described on
SGNewChannel
.
-
seconds
-
Specifies the number of seconds of sound data the sequence grabber is to work with at a time. To specify a fraction of a second, set this parameter to a negative fixed-point number. For example, to set the duration to half a second, pass in -0.5 in this parameter.
DESCRIPTION
You specify the number of seconds of sound data the sequence grabber is to work with at a time.
SPECIAL CONSIDERATIONS
You cannot call the
SGSetSoundRecordChunkSize
function during a record or preview operation, or after you have prepared the sequence grabber for a record or preview operation (by calling the
SGPrepare
function, described on
SGPrepare
).
This function may return a fraction (for details, see the discussion of the
seconds
parameter above).
RESULT CODES
|
paramErr
|
-50
|
Invalid parameter specified
|
|
cantDoThatInCurrentMode
|
-9402
|
Request invalid in current mode
|
SGGetSoundRecordChunkSize
The
SGGetSoundRecordChunkSize
function allows you to determine the amount of sound data the sequence grabber component works with at a time.
pascal long SGGetSoundRecordChunkSize (SGChannel c);
-
c
-
Specifies the reference that identifies the channel for this operation. You obtain this reference from the
SGNewChannel
function, described on
SGNewChannel
.
DESCRIPTION
SGGetSoundRecordChunkSize
returns a long integer that specifies the number of seconds of sound data the sequence grabber works with at a time.
SEE ALSO
You set the amount of sound data the sequence grabber component works with at any given time by calling the
SGSetSoundRecordChunkSize
function, which is described in the previous section.
SGSetSoundInputRate
The
SGSetSoundInputRate
function allows you to set the rate at which the sound channel obtains its sound data.
pascal ComponentResult SGSetSoundInputRate (SGChannel c,
Fixed rate);
-
c
-
Specifies the reference that identifies the channel for this operation. You obtain this reference from the
SGNewChannel
function, described on
SGNewChannel
.
-
rate
-
Specifies the rate at which the sound channel is to acquire data. This parameter specifies the number of samples the sound channel is to generate per second. If the sound channel cannot support the rate you specify, it uses the closest available rate that it supports--you can use the
SGGetSoundInputRate
function, described in the next section, to retrieve the rate being used by the channel. Set this parameter to 0 to cause the sound channel to use its default rate.
-
You can determine the rates that are valid for a sound channel that uses a sound input device by calling the Sound Manager (see
Inside Macintosh:
More Macintosh Toolbox
for more information about the Sound Manager).
RESULT CODES
|
cantDoThatInCurrentMode
|
-9402
|
Request invalid in current mode
|
|
deviceCantMeetRequest
|
-9408
|
Device cannot support grabber
|
SGGetSoundInputRate
The
SGGetSoundInputRate
function allows you to determine the rate at which the sound channel is collecting sound data.
pascal Fixed SGGetSoundInputRate (SGChannel c);
-
c
-
Specifies the reference that identifies the channel for this operation. You obtain this reference from the
SGNewChannel
function, described on
SGNewChannel
.
DESCRIPTION
SGGetSoundInputRate
returns a fixed-point number that indicates the number of samples the sound channel collects per second.
SEE ALSO
You set the rate at which the sound channel is collecting data by calling the
SGSetSoundInputRate
function, which is described in the previous section.
SGSetSoundInputParameters
The
SGSetSoundInputParameters
function allows you to set some parameters that relate to sound recording.
pascal ComponentResult SGSetSoundInputParameters (SGChannel c,
short sampleSize,
short numChannels,
OSType compressionType);
-
c
-
Identifies the channel for this operation. You provide your connection identifier. You connect to a channel component by calling the
SGNewChannel
or
SGNewChannelFromComponent
function, discussed on
SGNewChannel
and
SGNewChannelFromComponent
, respectively.
-
sampleSize
-
Specifies the number of bits in each sound sample. Set this field to 8 for 8-bit sound; set it to 16 for 16-bit sound.
-
numChannels
-
Indicates the number of sound channels used by the sound sample. Set this field to 1 for monaural sounds; set it to 2 for stereo sounds.
-
compressionType
-
Describes the format of the sound data. The following values are supported:
-
'raw '
-
Sound samples are uncompressed, in offset-binary format (that is, sample data values range from 0 to 255).
-
'MAC3'
-
Sound samples have been compressed by the Sound Manager at a ratio of 3:1.
-
'MAC6'
-
Sound samples have been compressed by the Sound Manager at a ratio of 6:1.
DESCRIPTION
You may use the
SGSetSoundInputParameters
function to control many parameters relating to sound recording. All of the sound parameters support two special values. If you set any of these parameters to 0, the sequence grabber does not change the current value of that parameter. If you set any of them to -1, the sequence grabber returns that parameter to its default value.
If you select a parameter value that the sound device cannot support, the sequence grabber returns an appropriate Sound Manager result code.
RESULT CODES
Sound Manager errors
SGGetSoundInputParameters
The
SGGetSoundInputParameters
function allows you to retrieve some parameters that relate to sound recording.
pascal ComponentResult SGGetSoundInputParameters (SGChannel c,
short *sampleSize,
short *numChannels,
OSType *compressionType);
-
c
-
Identifies the channel for this operation. You provide your connection identifier. You connect to a channel component by calling the
SGNewChannel
or
SGNewChannelFromComponent
function, discussed on
SGNewChannel
and
SGNewChannelFromComponent
, respectively.
-
sampleSize
-
Contains a pointer to a field to receive the sample size. The sequence grabber sets this field to 8 for 8-bit sound; it sets the field to 16 for 16-bit sound.
-
numChannels
-
Contains a pointer to a field to receive the number of sound channels used by the sound sample. The sequence grabber sets this field to 1 for monaural sounds; it sets the field to 2 for stereo sounds.
-
compressionType
-
Contains a pointer to a field that is to receive the format of the sound data. The following values may be returned:
-
'raw'
-
Sound samples are uncompressed, in offset-binary format (that is, sample data values range from 0 to 255).
-
'MAC3'
-
Sound samples have been compressed by the Sound Manager at a ratio of 3:1.
-
'MAC6'
-
Sound samples have been compressed by the Sound Manager at a ratio of 6:1.
DESCRIPTION
You may use the
SGGetSoundInputParameters
function to retrieve many parameters relating to sound recording. If you set any of the sound parameters to
nil
, the sequence grabber does not return that value.
© 1997 Apple Computer, Inc.Previous | Chapter Top | Chapter Contents | Next
